Programming with QuickTime VR

Getting Node Information

The QuickTime VR Manager function handlink "QuickTime VR Manager/QTVRGetNodeInfo" returns the node information atom container that describes a node and all the hot spots in the node. One of the atoms in a node information atom container is a node header atom, which contains the type and ID of the node, as well as the node name and any node comments.

Figure 4-7 is a diagram of a typical node information atom container.

The structure of a node header atom is described in "Node Header Atom Structure" .

Figure 7 Structure of the node information atom container

You can use standard QuickTime atom container functions to retrieve the information in a node header atom. For example, the MyGetNodeName function defined in Listing 4-3 returns the name of a node, given its node ID.

Listing 3 Getting a node's name



 
OSErr MyGetNodeName (QTVRInstance theInstance, UInt32 theNodeID, 

                                                                StringPtr theStringPtr)

{

    OSErr                   theErr = noErr;

    QTAtomContainer         theNodeInfo;

    VRNodeHeaderAtomPtr     theNodeHeader;

    QTAtom                  theNodeHeaderAtom = 0;

    

    //Get the node information atom container.

    theErr = QTVRGetNodeInfo(theInstance, theNodeID, &theNodeInfo);

    

    //Get the node header atom. 

    if (!theErr)

        theNodeHeaderAtom = QTFindChildByID(theNodeInfo, kParentAtomIsContainer, 

                                                    kQTVRNodeHeaderAtomType, 1, nil);

    if (theNodeHeaderAtom != 0) {

        QTLockContainer(theNodeInfo);

        

        //Get a pointer to the node header atom data.

        theErr = QTGetAtomDataPtr(theNodeInfo, theNodeHeaderAtom, nil, 

                                                            (Ptr *)&theNodeHeader);

        //See if there is a name atom.

        if (!theErr && theNodeHeader->nameAtomID != 0) {

            QTAtom theNameAtom;

            theNameAtom = QTFindChildByID(theNodeInfo, kParentAtomIsContainer, 

                                kQTVRStringAtomType, theNodeHeader->nameAtomID, nil);

            if (theNameAtom != 0) {

                VRStringAtomPtr theStringAtomPtr;

                

                //Get a pointer to the name atom data; copy it into the string.

                theErr = QTGetAtomDataPtr(theNodeInfo, theNameAtom, nil, 

                                                            (Ptr *)&theStringAtomPtr);

                if (!theErr) {

                    short theLen = theStringAtomPtr->stringLength;

                    if (theLen > 255)

                        theLen = 255;

                    BlockMove(theStringAtomPtr->string, &theStringPtr[1], theLen);

                    theStringPtr[0] = theLen;

                }

            }

        }

        QTUnlockContainer(theNodeInfo);

    }



    QTDisposeAtomContainer(theNodeInfo);

    return(theErr);

}

The MyGetNodeName function defined in Listing 4-3 retrieves the node information atom container (by calling QTVRGetNodeInfo ) and then looks inside that container for a node header atom with atom ID 1. If it finds one, it locks the container and then gets a pointer to the node header atom data. The format of this data is defined by the VRNodeHeaderAtom data structure:



 
typedef struct VRNodeHeaderAtom {

    UInt16                              majorVersion;

    UInt16                              minorVersion;

    OSType                              nodeType;

    QTAtomID                            nodeID;

    QTAtomID                            nameAtomID;

    QTAtomID                            commentAtomID;

    UInt32                              reserved1;

    UInt32                              reserved2;

} VRNodeHeaderAtom, *VRNodeHeaderAtomPtr;

The desired information, the node name, is contained in the string atom whose atom ID is specified by the nameAtomID field of this structure. Accordingly, the MyGetNodeName function then calls QTFindChildByID once again to find that string atom. If the string atom is found, MyGetNodeName calls QTGetAtomDataPtr to get a pointer to the string atom data. A string atom has this structure:



 
typedef struct VRStringAtom {

    UInt16                              stringUsage;

    UInt16                              stringLength;

    unsigned char                       theString[4];

} VRStringAtom, *VRStringAtomPtr;

Finally, MyGetNodeName copies the string data into the appropriate location and cleans up after itself before returning.